perm filename RAID.PMP[S,DOC]2 blob
sn#149403 filedate 1975-03-10 generic text, type C, neo UTF8
COMMENT ⊗ VALID 00027 PAGES
C REC PAGE DESCRIPTION
C00001 00001
C00004 00002 RAID SAILON #58.1 1
C00006 00003 RAID SAILON #58.1 2
C00011 00004 RAID SAILON #58.1 3
C00014 00005 RAID SAILON #58.1 4
C00018 00006 RAID SAILON #58.1 5
C00023 00007 RAID SAILON #58.1 6
C00027 00008 RAID SAILON #58.1 7
C00031 00009 RAID SAILON #58.1 8
C00036 00010 RAID SAILON #58.1 9
C00041 00011 RAID SAILON #58.1 10
C00046 00012 RAID SAILON #58.1 11
C00052 00013 RAID SAILON #58.1 12
C00057 00014 RAID SAILON #58.1 13
C00062 00015 RAID SAILON #58.1 14
C00067 00016 RAID SAILON #58.1 15
C00071 00017 RAID SAILON #58.1 16
C00076 00018 RAID SAILON #58.1 17
C00081 00019 RAID SAILON #58.1 18
C00087 00020 RAID SAILON #58.1 19
C00092 00021 RAID SAILON #58.1 20
C00093 00022 RAID SAILON #58.1 21
C00098 00023 RAID SAILON #58.1 22
C00102 00024 RAID SAILON #58.1 23
C00105 00025 RAID SAILON #58.1 24
C00110 00026 RAID SAILON #58.1 25
C00114 00027
C00115 ENDMK
C⊗;
RAID SAILON #58.1 1
+STANFORD ARTIFICIAL INTELLIGENCE LABORATORY FEB., 1971
+OPERATING NOTE 58.1
RAID X XXX XXXX
X I X X X X X
X S X X X X X
GOOD XXXXX X X X
F Y X X X X X
O O X X X X X
R U X X XXX XXXX
by Phil Petit
ABSTRACT:::
Raid is an interactive debugging program which uses
the displays and allows dynamic monitoring of memory locations.
This work was supported by the Advanced Research Projects Agency
of the Department of Defence under contract SD-183.
RAID SAILON #58.1 2
Raid is a debugging program (RAID -- kills bugs -- get it?).
Raid lives in core with your program and allows you to do various
things with and to your program, such as stop at selected places and
examine your core image, etc. The major advantage of Raid over DDT,
is that Raid uses the displays to give you a constantly updated view
of selected locations in core. Consequently, however, this means
that Raid cannot be used from a teletype.
The first step in using raid is having a program to debug. For
most of us this is the hardest part. The second step is to get Raid
and the program loaded together:
LOADING RAID::::::::
The loader will load Raid with your program if you use the /V
switch. For example if the binary file for your program was called
FNORP, the loader command /VFNORP$ (where $ means alt-mode) would
cause the loader (on a good day) to load Raid with your program.
Additionally, if your project-programmer number is in a special
list in the system, Raid will be loaded instead of DDT when you type
DEBUG. Ask a system programmer how to get your project-programmer
number on this list.
Once you have your program and Raid in core, you must get into
Raid. This is done by typing DDT<cr> to the system. This is because
the system can't tell the difference between Raid and DDT. Stupid
system. When you type DDT your display screen will flash and at the
+top will appear the name of the program loaded right after RAID,
+listed twice. The duplexing of keyboard input will move down to the
bottom of the screen. If it runs off the bottom of the screen so
that you cannot see it, you can get it back by typing several dozen
carriage returns. Raid is now ready to accept commands. The first
command you will want to type will probably be the one which points
Raid at your symbol table, but we must now pause in this tale of
drama at the keyboard and discourse on the format of commands.
COMMAND FORMAT:::::::::::
Raid commands consist of two parts, the first of which may
sometimes be absent. The first part is a value, and the second is a
command character, which may or may not have control bits with it.
Values:
A value can be a single number or defined symbol (like one of
your labels), or an arithmetic expression involving numbers and/or
symbols, or a machine instruction in standard assembler format, etc.
RAID SAILON #58.1 3
Below is a list of the various value formats and what they mean.
(Arithmetic is integer.)
VAL1 VAL2 sum of VAL1 and VAL2
VAL1+VAL2 sum of VAL1 and VAL2
VAL1-VAL2 obvious
VAL1*VAL2 product (multiplication) of VAL1 and VAL2
VAL1/VAL2 quotient (division) of VAL1 by VAL2
(VAL) this causes the two halves of VAL to be swapped
VAL, if not followed immediately by another comma,
this causes the value to be truncated to four
bits and shifted left 23 (decimal) positions. To
save you some calculating, that puts it in the
accumulator field.
VAL,, this causes VAL to be placed in the left half
(i.e. shifted left 18 places).
@ @ has the value 20,, i.e. the indirect bit
. "." has the same special meaning as in the
assembler i.e. the place you currently are.
+<ctrl 1>. has the value of the contents of ".".
+
+VAL <ctrl 1>. has the value of the contents of VAL .
In addition, the following funny things exist:
= in front of a digit string causes the string to
be interpreted as decimal instead of octal.
" followed by a chr., followed by a string not
containing that chr., followed by that chr., has
the value of the left adjusted ascii of the first
5 or fewer characters in the string.
+<ctrl 1>" is just like " except that up to 25 words or so
RAID SAILON #58.1 4
+ can by typed between the delimiters. These words
+ are deposited in successive locations (starting
+ with ".") when you type a carriage return or ">"
+ or "<" (see commands for changing locations
+ below). If one of these commands does not
+ immediately follow the trailing delimiter, the
+ whole value is ignored.
' is just like " except that it is sixbit.
<ctrl 1>' (this means the ' character with the control-1
key down) this causes the string of characters
following it, up to the first non-letter
non-digit character to be converted to radix50,
and has that value.
<ctrl 1>% followed by a string of values(not containing
comma) seperated by commas, causes the values in
the string after the first to be considered bytes
of a size indicated by the first value in the
string.
EXAMPLES::::
=10 has the value 12 (octal)
"/POT/ has the same value as ASCII /POT/ has in the
assembler, namely -- 502372400000
'/DSK/ has the same value as SIXBIT /DSK/ has in the
assembler, namely -- 446353000000
<ctrl 1>%3,5,4,3,7,0,7,1 has the value 543707100000
RAID COMMANDS::::::
Raid commands consist of a single character, sometimes with
control bits, sometimes preceded by a value. In the following
discussion, <ctrl 1> preceding a character will mean that character,
typed with the control-1 key down. Similarly, <ctrl 2> will indicate
the control-2 key, and <ctrl 12> will indicate both keys.
The following things should be kept in mind. Raid allows you to
see the contents of various locations in core by displaying or
"opening" these locations on your display screen. It places a
pointer next to the most recent location opened. These locations are
RAID SAILON #58.1 5
usually displayed in the order in which they are asked for, starting
at the top of the screen and going down. One exception to this is
the < command; the other is if the location already appears on the
screen. In the first case, locations are displayed going up the
screen; in the second case, the pointer is moved to the place on the
screen where that location is already displayed. There is a maximum
number of locations which can be displayed at one time. This maximum
number can be set with the I command, and is initially 10 (i.e. 8).
When the bottom of the screen (based on the maximum number) is
reached by the pointer, it wraps around to the top, and starts
replacing the locations there with the new ones. When the pointer
reaches the top while moving up, it wraps around to the bottom.
The normal pointer consists of a "both-ways arrow" (↔), but
there are two other kinds of pointers which are used sometimes. They
are left arrow (←) and right arrow (→). The both-ways arrow is the
main pointer, and, as long as there is no right arrow on the screen,
the location pointed to by the both-ways arrow is the value of "dot"
(i.e. . ). However, if there is a right arrow on the screen, the
value of "dot" will be the location pointed to by the right arrow.
In the following discussion of the Raid commands, the phrase "the
location pointed to" will always refer to the location whose value is
"dot", i.e. the location pointed to by the right arrow, if any; else
the location pointed to by the both-ways arrow. This all sounds
fairly confusing, but the confusion is in the description rather than
in what Raid does.
Locations are opened and displayed in various modes. Raid
initially opens locations in "cymbolic" mode (symbolic?). This means
that words are displayed, as much as possible, as machine
instructions in standard assembler format. All this can be changed,
however, with the mode commands listed below. All the mode commands
use one or more control bits (they are all typed with one or more
control keys), and the significance of the different combinations of
control bits is the same for all of them. If a mode command is typed
with only the <ctrl 1> bit, the mode of the location pointed to by
the both-ways arrow is changed, and nothing else. If it is typed
with <ctrl 2>, then the mode in which FUTURE locations are opened is
changed, until a carriage return is typed, at which point the mode
reverts to the "standard" mode -- initially cymbolic. If it is typed
with both control bits (<ctrl 12>) the mode for future locations is
changed as with <ctrl 2>, but the "standard" mode is also changed.
Note that with both the <ctrl 2> and the <ctrl 12>, none of the modes
of locations already on the screen is changed.
C This sets the mode to "cymbolic". This means that words
will be displayed as machine instructions, if possible, and
that fields (address, index, etc.) will be displayed as
RAID SAILON #58.1 6
symbols from your symbol table (see below) plus or minus an
offset, if possible. See appendix A for a full discussion
of this mode and the parameters which determine what it
does.
O This sets the mode to "octal". Words are displayed as
octal (base 8) numbers, except that a space is inserted
between the left and right halves of words if the left half
is not zero.
D This displays words as decimal numbers, preceded by an
equal-sign (=).
F This displays words as decimal floating-point numbers,
unless they are not normalized, in which case they are
displayed in decimal mode (above).
H This is half-word mode. The left and right halves of the
word are displayed, symbolically (i.e. as symbols from
your symbol table, plus or minus an offset), separated by a
double comma.
T This is ascii, or 7-bit type-out mode. The word is
considered to contain 5 characters of 7 bits each, left
adjusted in the word and these 5 characters, plus a
possible sixth if the low order bit is on, are displayed.
Carriage return, line feed, and form feed appear as a small
CR, LF, and FF, respectively. If the high order 7 bits
(first character) in the word is 0 (null), the word is
considered to contain right adjusted ascii.
VAL T This is for other character type-out modes. Legal values
for VAL are: 7 for ascii (as above), 6 for sixbit, and 5
for radix50.
Q This is byte-pointer mode. The word is displayed in
exactly the format used by the assembler POINT pseudo-op,
that is, the word POINT followed by a size field, followed
by a comma, then the address, index, etc., then possibly
another comma and a position. The size and position are
decimal.
VAL V This is byte mode -- the output analog of the <ctrl>% input
mode. The word is typed out as an appropriate number of
bytes, separated by commas. The bytes themselves are typed
in octal. The VAL is the byte size and should not be
negative. A byte size of 0 has a special meaning which is
described in appendix A.
RAID SAILON #58.1 7
A This is absolute mode. This one is different from all the
others in that it does not change the basic mode of the
mode being changed, but merely indicates that, while the
word is being typed out in the same mode as before (the
last mode indicated for it), addresses and other fields are
typed as numbers instead of symbols.
U This is the same as cymbolic mode except that the address
field (right half of the word) is considered to be up to
three right-adjusted ascii characters and is typed that
way.
VAL U This is as above except that VAL indicates: if it is 5,
then radix50 for the address field, if it is 6, then
sixbit, and if it is 7, then ascii, as above.
The following is a listing of the commands to examine and change
core.
VAL <ctrl 1> : This points Raid at the symbol table for the
program indicated by VAL. In this case, VAL
should be a single identifier.
VAL <ctrl 1> & This points Raid at the symbols (within the
program it is already pointing at) for the block
indicated by VAL. Again, VAL should be a single
identifier. If you don't use block structure,
ignore this command.
VAL ; This causes the location VAL to be displayed. If
it is already on the screen, Raid just moves the
pointer to that position, otherwise, it displays
it in the next location on the screen.
VAL <ctrl 1> ; This causes the location VAL to be displayed as
above, except that the location is also
protected. This means that a star appears on the
screen to the left of the location and that
location cannot be erased from the screen.
<ctrl 1> ; This, which is the same command as above, but
without the VAL, causes the location Raid is
currently pointing to to be protected.
<ctrl 2> ; This causes the location Raid is currently
RAID SAILON #58.1 8
pointing to to be unprotected.
> This causes Raid to display the next higher
location from the one it is currently pointing
at. For example, if it is currently pointing at
location 36, this command would cause it to
display (and point at) location 37. If the
location is not already on the screen, the
pointer moves down one position to display this
next location.
< This causes Raid to display the next lower
location from the one it is currently pointing
at. For example, if it is currently pointing at
location 36, this command would cause it to
display location 35. If the location is not
already on the screen, the pointer moves UP one
position to display this next location.
<ctrl 1> > This causes Raid to move its pointer down one
position without changing what location is
displayed there. As always, if the pointer is at
the bottom, moving down causes it wraps around to
the top.
<ctrl 1> < This causes Raid to move its pointer up one
position. As always, if it is at the top, moving
up causes it to wrap around to the bottom.
<ctrl 2> > This is the same as > without any control, except
that instead of displaying the new location in
the current mode, it displays it in the same mode
as the location it is currently pointing to. For
example, if you open the first word of your
teletype buffer, and change the mode for it to
ascii, you can then open the second word of the
buffer in ascii by using this command.
<ctrl 2> < This is the same as < except for mode as above.
<ctrl 12> > This is the same as <ctrl 1> > except for mode as
above.
<ctrl 12> < This is the same as <ctrl 1> < except for mode as
above.
VAL <ctrl 1> I This causes the number of lines Raid is willing
to display to be set to VAL. This number is
initially 10 (i.e. 8).
RAID SAILON #58.1 9
<ctrl 1> I This causes the number of lines Raid is willing
to display to be increased by 1.
<ctrl 2> I This causes the screen to be cleared of all
displayed locations. This puts the screen back
to the condition it was in when Raid was first
loaded, except that it does not change the
program or block pointed to.
<cr> Carriage return, not preceded by a value, has no
effect except to cause the screen to be updated.
VAL <cr> Carriage return, preceded by a value, causes that
value to be placed in the location currently
pointed to (by the right arrow, if any, else by
the both-ways arrow). That is, the location
+ whose value is dot (i.e. . ). If the mode of
+ the first or only part of VAL typed can be
+ recognized by the input format as text, Decimal,
+ Octal, Real or Cymbolic, VAL will be displayed in
+ that mode, no matter what the current mode
+ settings are. You may then change the mode.
VAL > This has the same function as > except that the
VAL is first placed in the location pointed to,
as with carriage return. ALL forms of > and <
(as well as TAB and all forms of [, ], and @) act
as if they were preceded by a value and carriage
return, if they are preceded by a value; i.e.
they deposit that value in the location currently
pointed to before having their standard effect.
These commands are not all listed seperately.
<TAB> Tab causes the location whose address is in the
right half of the word currently pointed to by
the both-ways arrow to be displayed. Note that
if TAB is preceded by a value, that value is
first placed in the location pointed to, and THEN
the location indicated by the right half OF THAT
VALUE is opened.
; A semicolon, with no control bits and not
preceded by a value, causes the location
indicated by the right half of the word currently
pointed to by the both-ways arrow to be opened,
as with TAB, except that, while the both-ways
arrow moves to point to the new location, a right
arrow is left behind at the old location, except
RAID SAILON #58.1 10
if there is already a right arrow on the screen,
in which case, the right arrow stays where it is.
This means that the value of dot is not changed,
and that if something is deposited, it is
deposited in the old location (where the right
arrow is). Note, however, that if a further
semicolon is typed (by itself), the location
opened will be the one indicated by the right
half of the new word, the word pointed to by the
both-ways arrow. Note also that typing this
command preceded by a value converts it to a
different command; see above.
<ctrl 1> [ This has the same effect that semicolon by itself
has, namely it opens the location indicated by
the right half of the word pointed to by the
both-ways arrow, but does not change dot; except
that it can be preceded by a value, in which case
that value is deposited in the location currently
pointed to (by the right arrow, if any -- i.e.
dot) BEFORE opening the location indicated.
<ctrl 2> [ This has exactly the same effect as TAB. Note
that preceding it with a value causes that value
to be deposited BEFORE opening the indicated
location.
<ctrl 1> ] This has the same effect as <ctrl 1> [ except
that it uses the left half, instead of the right
half. Again, it leaves a right arrow behind,
unless there is one already, and it may be
preceded by a value, which will be deposited
BEFORE opening the indicated location.
<ctrl 2> ] This has the same effect as <ctrl 2> [ except
that it uses the left half. This one can be
preceded by a value too. If you think you're
getting tired of reading all this detail, think
how tired I am of typing it.
<ctrl 1> @ This has the same effect as <ctrl 1> [ except
that it uses the EFFECTIVE ADDRESS of the
location currently pointed to by the both-ways
arrow. Yet again it leaves behind a right arrow
(if none yet) and may be preceded by a value.
You can figure out what happens if it's preceded
by a value, can't you?
<ctrl 2> @ I bet you can figure this one out by yourself.
RAID SAILON #58.1 11
That's right, it has the same effect as <ctrl 2>
[ except it uses the effective address instead of
the right half.
<ctrl 12> [ This and the next two commands are a little
complicated. This causes the location currently
pointed to by the both-ways arrow to be protected
(remember the little star that keeps things on
the screen?), then opens and protects the
location addressed by the right half of the
location pointed to by the both-ways arrow, but
does so DYNAMICALLY. This means that whenever
the right half of the word pointed to by the
both-ways arrow changes (that is, the word which
was pointed to by the both-ways arrow at the time
this command was given), the location which was
caused to be displayed by this command is changed
to be the location NOW indicated by the right
half of the word which was pointed to by the
both-ways arrow at the time the command was
given. Is that clear? Perhaps an example would
help. Suppose you wanted to keep track of the
top location of the stack. You would say P; ,
which would cause the push-down pointer (which
everyone but DEC calls P) to be displayed (and
pointed to). Then you would say <ctrl 12>[ .
This would cause the P location to be protected,
then would open the location addressed by the
right half of P, and cause it to be protected.
However, from then on, whenever P changed, the
location you just displayed would change to be
the location addressed by the right half of P --
or the top location of the stack.
A few special things are true of the location
opened by this command. First of all, you should
avoid pointing to this location on the screen and
trying to deposit in it. You will wind up
depositing in a table inside Raid, and your
screen will do funny things. You are helped in
this by the fact that this command leaves a right
arrow behind, so the only way of pointing to this
funny location is with the <ctrl 1> > command
and its friends. If you open this same location
by normal means, it will be opened in another
place on the screen, and you can deposit in it
there. For example, if, in the P example above,
the right half of P addressed location 300, and
you said 300; , you would get location 300
RAID SAILON #58.1 12
opened in two places on the screen. The old one
would be the dynamic one, and the new one would
be an ordinary one.
It is possible to "chain" this command with
itself (or with the next two, in any order or
combination), for as many locations as you have
room on the screen. For example, if, in the P
example we have been belaboring, you had said
<ctrl 12>[ twice, instead of once, you would
have opened the location addressed by the right
half of the word on the top of the stack. This
is all dynamic -- now to two levels -- so that if
P changes, you have displayed, not only the new
thing that P points to, but also the new thing
that the new top of the stack points to.
Note, finally, that if this command, or either of
the next two, is preceded by a value, that value
is deposited in the location currently pointed to
(by the right arrow, if any), as above, BEFORE
the operation takes place.
<ctrl 12> ] This is exactly the same as the <ctrl 12>[
command above, in all its confusing glory, except
that it uses the LEFT HALF instead of the right
half. Will wonders never cease? No.
<ctrl 12> @ This is exactly the same as the <ctrl 12>[
command above, in all its confusing glory, except
that it uses the EFFECTIVE ADDRESS instead of the
right half. Will wonders never cease? Yes.
VAL <ctrl 1> = This causes a word inside Raid to have VAL (not
the contents of VAL, but VAL itself) deposited
into it, and that location to be displayed on the
screen. The location is opened in octal mode,
but the mode can be changed, as with any other
location displayed. This cammand leaves a right
arrow behind, if there isn't already one. This,
then, is a way of seeing what some value is in
other modes. For example, you might want to see
what the octal value of the label FOO is (say
FOO<ctrl 1>=), or what the cymbolic
representation of 346 might be.
RAID SAILON #58.1 13
VAL : VAL should be a single identifier. This command
causes a symbol, or label, with the name of
whatever VAL is, to be created and put into your
symbol table. The symbol is put into the block
you are currently inside, and is given the value
of the current value of dot, i.e. the location
currently pointed to.
VAL ← This command differs in format from the standard.
It should be followed by another value, VAL1.
VAL should be a single identifier, but VAL1 may
be any value. This command creates a symbol with
the name VAL (as does the : command), but sets
its value to VAL1. VAL1 should then be followed
by a carriage return.
VAL <ctrl 1> K This causes the symbol VAL (which should be a
single identifier) to have a bit turned on in its
symbol table entry which causes Raid to not use
the symbol for typing out the contents of
locations. In other words, this has the same
effect as using double left arrow (←←) in the
assembler.
VAL <ctrl 1> W This is the word-search command. The general
effect is to find all words which have VAL in
them. Specifically, Raid searches core, between
certain limits, which may be set (see below), for
words which match VAL (not the contents of VAL,
but VAL itself) in all bit positions which are on
in location $M. That is to say, two words are
compared by XORing them, and then ANDing the
result with location $M. If this produces 0, the
words to match. Raid continues to search,
opening each location which matches, until it
comes to the end of the range, or until it has
found enough matches to half-fill the display
locations available, at which time it stops and
prints a big star (*) on your screen. You may,
at this point, type ∨ (the "or" key) to continue
the search, and Raid will pick up where it left
off, stopping when it has again half-filled the
screen; or you may type any other command. (No
characters are lost.) However, if you do not let
a search run to completion, the next search you
RAID SAILON #58.1 14
do will take up where the last one left off. You
can, at any time later, type ∨ and continue the
last search you did.
VAL <ctrl 1> N This is not-word-search. This works exactly like
word-search, except that words are considered to
match only if they are different in some bit
which is on in $M.
VAL <ctrl 1> E This is effective address search. It works like
word-search except that for each word examined,
the effective address is calculated, and this
effective address is matched with VAL. The mask
in $M is not consulted, and words are considered
to match if VAL and the effective address are
exactly the same.
+VAL <ctrl 2> E The contents of VAL are converted to text as if
+ for displaying. The mode used is VAL's current
+ screen mode if VAL is on the screen; otherwise
+ the current display mode. This text is sent to
+ the system line editor, allowing one to edit it
+ as in the SOS "Z" command. A carriage return
+ terminates the command, causing the edited text
+ to be read, like any other input, and the
+ resultant value deposited in ".". If VAL is
+ omitted, "." is assumed.
+
+
+VAL <ctrl 1> Z A list is kept of the names of the last few
+ blocks opened. This command goes back VAL
+ blocks, and re-opens that one. There is never
+ more than one copy of the same block name in the
+ list. If VAL is omitted, 1 is assumed.
+
+
+ <ctrl 2> Z The above list is forgotten. Then a new one is
+ started, beginning with the currently open block.
+
+ <ctrl 12> Z The block at the newest end of the above list is
+ re-opened. For instance, after the sequence
+ FOO<ctrl 1>Z
+ BAZ<ctrl 1>Z
+ GLUB<ctrl 1>Z
+ 2<ctrl 12>Z,
+ FOO has been re-opened. Then the command
RAID SAILON #58.1 15
+ <ctrl 12>Z would have the same effect (opening
+ GLUB again) as would -2<ctrl 1>Z.
∨ (The "or" key). This causes the last search you
did to be continued. If you have done no
searches, or if the last search you did has
already run to completion, this command does
nothing.
VAL ∪ This causes the lower search bound, for the next
search only, to be set to VAL. At the completion
of the next search, this bound will be set back
to its original value.
VAL <ctrl 1> ∪ This causes the lower search bound to be set
permanently to VAL. This sets the value back to
which the search bound will be set at the
completion of a search.
VAL ∩ This sets the upper search bound, for the next
search only.
VAL <ctrl 1> ∩ This sets the upper search bound permanently.
The following section describes the Raid commands which allow
you to run your program in various ways. These include the commands
for manipulating breakpoints, which cause your program to pause when
it gets to selected places, so that you can poke at it and see what's
wrong. There are also single step features which allow you to run
you program one instruction at a time, while displaying important
locations.
Associated with several commands (including the searches above),
is a big star (*), which Raid prints on your screen to let you know
it is done with something which may have taken it a while. This
star, in all cases, is removed the next time Raid recieves input --
usually as soon as you type anything.
VAL <ctrl 1> G This is the go command. It causes Raid to start
running your program at location VAL. Raid
actually transfers to your program, so your
RAID SAILON #58.1 16
program will continue to run until it hits a
breakpoint, if any, or you say control-C, or your
program exits or does something the system
doesn't like.
<ctrl 1> G The go command, without a value, starts your
program at its starting address, i.e. the
address in the right half of JOBSA.
VAL <ctrl 1> B This causes Raid to plant a breakpoint at
location VAL in your program. What Raid actually
does, is change this location to a JSR to a
certain location in Raid, remembering what the
location used to be. This means that when your
program gets here, it will JSR to Raid, at which
point Raid will put the location back to what it
was, open the break-point location on the screen
and print a big star on the screen. You are now
in Raid and can type commands to it. If you
examine locations, or move the both-ways arrow in
any other way, Raid leaves behind it a left
arrow. Raid always prints a left arrow at the
next location your program should execute, if
that location is on the screen, and if the
both-ways arrow is not there.
VAL <ctrl 2> B This removes the break-point, if any, at location
VAL.
<ctrl 2> B This removes all break-points.
<ctrl 1> P This causes Raid to continue running your program
from where it left off. If your program hit a
breakpoint, Raid will continue your program with
the breakpoint instruction (executing the real
instruction there), and your program will run
until it hits another (or the same) break-point,
etc. If you have been stepping your program (see
below), Raid starts it up at the next location to
be executed.
VAL <ctrl 1> P This causes Raid to procede (as above) from the
current break-point (the last one you hit), VAL
times. That is, it has the effect of saying
RAID SAILON #58.1 17
<ctrl 1> P, VAL times, as long as you hit the
same preakpoint each time. If you hit other
breakpoints in between, you will stop, then if
you procede from them and hit the old breakpoint,
the counting will continue. See appendix B for
details of getting out of this, etc. This
description is not, I realize, totally
unambiguous. When a description is ambiguous,
keep in mind that Raid generally does the right
thing.
<ctrl 1> ← This causes Raid to open, on the screen, the next
location your program is going to execute, i.e.
the next step location, or the last break-point
you hit.
<ctrl 1> S This is the basic step command. It causes the
next location in your program (the next location
to be executed; the left arrow location) to be
stepped. This means that the instruction has its
effect, and then you are back in Raid. It is as
if you had planted a break-point on the next
instruction you would get to, and proceded.
After stepping, Raid opens the next location (the
next one you will execute). It does not print a
star. If the instruction you step skips one
instruction, Raid also displays the instruction
skipped.
<ctrl 2> S This is exactly like <ctrl 1> S except that
instead of stepping the next instruction of your
program, it steps the instruction currently
pointed to (by the RIGHT arrow, if any, else by
the both-ways arrow -- i.e. dot). It then opens
the location that that gets you to, and it
becomes the next location to be executed. Note
that this is a way of getting started with
stepping, if you haven't run any of your program
yet, or if you want to change the flow of your
program.
<ctrl 1> X This is the basic execute instruction. It has
the same effect as <ctrl 1> S, except if the
instruction to be stepped (executed), is a
subroutine call instruction (JSR, PUSHJ, JSA, or
RAID SAILON #58.1 18
JSP), or a user UUO. In these cases, it treats
the instruction, and the subroutine (or UUO
routine) it calls, as one instruction. This
means that your program starts running at the
subroutine call (or UUO), and runs until it
returns, and stops on the instruction it returns
to. This instruction is then opened. Note that
if you STEP a user UUO, you wind up inside your
UUO routines. There is a restriction involved in
this command, and it applys also to the next two
commands (the other two X commands). The
restriction concerns how many locations a
subroutine (or UUO) may skip. The maximum is 7.
If you execute a subroutine call, or a UUO,
(currently no system UUO skips more than 1,
except INIT, which is handled as a special case
by Raid.), and it skips more than 7 locations,
you will wind up in a funny place in Raid and all
sorts of wrong things will happen. A few words
should be said about break-points in executed
subroutines. In general, they work. You may hit
a break-point inside a subroutine, the call to
which was executed, and you may then step and
execute other instructions. When you procede
from the breakpoint, you will get back when the
subroutine exits, just as if you hadn't hit any
breakpoints. You should NOT step the subroutine
return, as you will wind up stepping locations
inside Raid. If you do this accidently, and
haven't gone too far, you may procede (<ctrl 1>P)
and the right thing will happen. You may nest
executes to a level of 8. You should avoid
executing subroutine calls which you don't return
from, as you will remain inside the subroutine,
as far as Raid is concerned, until you do return,
and this will decrease the number of levels you
can nest subroutines.
<ctrl 2> X This works just like <ctrl 1>X except that it
starts with the instruction currently pointed to.
VAL <ctrl 12> X This causes the instruction VAL (VAL itself, not
the instruction at VAL) to be executed as though
it was in your program. Executing the
instruction has no effect on which instruction is
the next instruction to be executed, even if VAL
is a jump or skip. VAL may be a subroutine call,
RAID SAILON #58.1 19
in which case the right things happen. The
restrictions listed above for executing
subroutine calls apply. Note that executing a
JRST with this command has no effect (except
possibly on flags).
VAL <ctrl 12> Y This has the same effect as <ctrl 12>X if VAL is
a subroutine call. Otherwise, the instruction is
just plain (vanilla) executed, regardless of what
it is. Even jumps are not interpreted. If the
instruction does not jump, it should not skip
more than two, and control reverts to Raid as
with <ctrl 12>X. If the instruction does jump,
you are off and running, as with <ctrl 1>G, until
you hit a breakpoint or something. The purpose
of this instruction is to augment the <ctrl 1>G
command. It is to be used with things like
flag-restoring JRSTs, and such, and has only
minimum utility, except in the exec Raid version.
<ctrl 12> S This is the multi-step command. It has, except
as noted below, the same effect as repeatedly
saying <ctrl 1>S. It steps the current location,
updates the screen (displaying the next
instruction to be executed), steps the next
instruction, updates the screen, and so on. It
keeps running until either you type a key, in
which case it stops and returns control to Raid
(the character you type may be anything, and is
ignored); or it gets to a subroutine call or
subroutine return instruction (Subroutine return
instructions are: POPJ, JRA, and JRST @). When
it reaches one of these, it pauses and displays a
big star. If you type S, and it is a subroutine
call, it steps the call and continues with the
multi-stepping. If you type X and it is a
subroutine call, it executes the subroutine call
and continues with the multi-stepping. If you
type S or X and it is a subroutine return, it
continues with the multi-stepping. If you type
anything else (except as noted in appendix B),
for instance space, it returns control to Raid,
and you must type <ctrl 12>S to restart
multi-stepping. UUOs are treated as subroutine
calls.
RAID SAILON #58.1 20
This ends the discussion of Raid commands. You now know as much
as (more than?) you need to to use Raid. It is suggested that at
this point you go poke at Raid a little to become familliar with it.
If you want, you may read the appendices at this time, but it is
probably better to wait until you have used Raid and are more
familliar with it.
RAID SAILON #58.1 21
APPENDIX A
CYMBOLIC MODE::::::::::::::::::::
This describes how cymbolic mode decides how to display a word.
If the left half of the word is 0, it is displayed in halfword mode.
If the left half is all ones, the word is printed as a negative
number. If the left-hand nine bits (opcode) is 0 or 777, the word is
printed in halfword mode. Otherwise, if there is an entry for the
opcode, the word is printed as an instruction. If there is no opcode
entry, an opdef entry is searched for, and if none is found, the word
is printed in half-word mode.
If the word is printed as an instruction, the index and
accumulator fields are printed as symbols only if there is an exact
match, otherwise as numbers.
PRINTING SYMBOLS:::::::::::::::::
When Raid is going to print a number, unless it is in absolute
mode, or some mode where numbers are always printed as numbers, it
tries to print the number as a symbol, plus or minus an offset. To
do this, Raid first searches the symbol table for the two best
matches with the number it has, one greater, the other less. If the
number is less that 140, Raid requires an exact match, or it prints
it as a number. Otherwise, if it has found an exact match, it prints
that symbol. If not, it goes through some contortions to decide
which close match to use, and whether or not it will use either.
There are four parameters it uses in deciding. These parameters are
stored at location $C ff. The first parameter, the one at $C, is the
maximum plus offset. The second one, at $C+1, is the maximum minus
offset. Both of these numbers start out at 77, but may be changed.
The value is anded with 777 before use. The third parameter we will
call S, and is initially 10, the fourth parameter we will call Q, and
is initially 40. We will call the plus offset P, and the minus
offset M. Raid first compares P and M with their respective maxima.
If both are too big, the number is printed as a number. If P is too
big but M is not, then M is used (the minus one). If M is too large,
but P is not, then P is used. If both are within the limits, then
the fuction F=((P*Q)/100)-S-M is calculated, where 100 is octal.
If F is positive, M is used, otherwise, P is used. This means that S
and Q are relative weighting parameters; S is additive weighting, and
Q is multiplicative. Notice that if Q=100 and S=0, Raid uses the
smaller of M and P. If Q is instead 40, P is used unless it is twice
RAID SAILON #58.1 22
as big as M. On the other hand, if Q=100, but S=10, P is used unless
it is greater that M by more than 10.
BYTE SIZE 0:::::::::::::
If the byte size in the V mode command, or in the <ctrl 1>%
input string is 0, the bytes are interpreted acording to a mask in
location $M+1. Bytes may be any sizes, and the boundaries are
indicated by a change from 0's to 1's, or vice-versa, in this mask.
For example, if $M+1 contains 707070707070, this would indicate 3-bit
bytes. 770077007700 would indicate 6-bit bytes. 741703607417 would
indicate 4-bit bytes. 770770770770 would indicate a 6-bit byte,
followed by a 3-bit byte, followed by a 6-bit byte, followed by a
3-bit byte, etc. 252525000000 would indicate 18 one-bit bytes
followed by a 18-bit byte.
RAID DEFINED LOCATIONS::::::::::::::::::
+These are all global symbols. You can declare them EXTERNAL, then
+write clever programs to poke at them.
RAID This is the starting address of Raid.
DDT This is the same as RAID.
DDTEND This is the first unused location after Raid. It is not
very useful now that the loder moves the symbol table down
(up?) to just beyond the last program loaded.
$C This and the three locations following it are the
parameters for deciding how to print symbols. See above.
$M This location is the search mask. It is initially set to
-1. See the search commands.
$M+1 This is the byte mask for 0 byte size. See above.
+$M-1 This location may contain a String address or byte pointer
+ which behaves like the breakpoint String byte pointer (see
+ Breakpoints, appendix B) whenever you jump to DDT from your
+ program. It is zeroed after each use.
+
RAID SAILON #58.1 23
+$IO If non-zero, words which represent machine I/O instructions
+ (CONI, DATAO, BLKO, etc.) will be printed as such in
+ Cymbolic mode. Otherwise they will be treated as the UUO's
+ PPIOT, MAIL, INTUUO, etc., which share some of the same
+ Opcodes, or as simply negative numbers if no such UUO
+ exists for this word.
$I This is the location where Raid keeps its current idea of
your program counter -- the address of the next instruction
to be executed. Breakpoints JSR to this location. The
left half contains your program flags. If you change the
left half of this word, you will change what program flags
get restored each time your program is started up.
$1B to $20B These 20 locations, and the four locations following
each of them, are the breakpoint table. For a detailed
description of what each contains, see appendix B. The
first word is the address of the breakpoint. The location
is -1 if this breakpoint is unused. The second location is
the multiple procede count. The third location is the
conditional skip instruction. The fourth location is
string-breakpoint byte pointer. The fifth location is the
real contents of the breakpoint location.
RAID SAILON #58.1 24
APPENDIX B
BREAKPOINTS::::::::::::
You may have a maximum of 20 (octal) breakpoints at any one
time. The breakpoint information is contained in a table, with five
locations for each breakpoint. The first location of each of the 20
enties is given a label of the form $nB, where n is a number from 1
to 20. This first location of each entry contains the address of the
breakpoint in your core. It is -1 if this breakpoint is unused.
Entries are assigned to breakpoints in the order in which breakpoints
are created, starting with $1B. The real contents of the breakpoint
location are stored in the fifth of the locations in the table entry
(i.e. $nB+4). Changing this location, however, has no effect,
because the real contents are replaced in your core while you are
talking to Raid, and the JSR is placed there only while your program
is running. The second location in each entry ($nB+1), contains the
multiple procede count for that breakpoint. This is where Raid puts
the count if you say VAL <ctrl 1> P. This count is counted down by 1
each time you hit this breakpoint and the breakpoint is ignored (you
procede automatically) if the count is still positive. Depositing a
number here will have the same effect as using multiple procede.
Depositing 0 here will get you out of a multiple procede.
The third word of each entry is the skip instruction. If this
instruction is non-zero when Raid hits this breakpoint, Raid executes
the instruction (which may be a subroutine call), and what Raid does
with the breakpoint depends on whether or not this instruction skips.
If the instruction does not skip, Raid does the normal thing (what it
would have done if this word had been 0), namely, it counts the
multiple procede count and procedes if it is positive, stops if it is
zero or negative. If the instruction skips one, Raid does not count
the multiple procede count, but rather it stops at the breakpoint
anyway. If the instruction skips two, Raid does not count the
multiple procede count, but rather it procedes (ignores the
breakpoint), anyway. The instruction had damn well better not skip
more than two.
The fourth location in each entry ($nB+3) is the string
breakpoint pointer. If it is not zero, then it is assumed that the
right half points to (addresses) the start of an ASCIZ string. It
+had better. The left half, if non-zero, implies that the word is a
+byte pointer such that ILDB on it will fetch the first String
+character. If it's zero, a byte pointer to the first character in
+the word will be constructed. This ASCIZ string is then scanned by
the input scanner, just as if you were typing those characters on your
RAID SAILON #58.1 25
keyboard, every time you stop at this breakpoint. This means that if
you want to display a certain location each time you hit a certain
breakpoint, you can put in the appropriate location a pointer to an
ASCIZ string consisting of FOO; (to open location FOO). When the
string runs out, Raid takes input from the keyboard. If you have
been paying attention, you are probably asking yourself "how do I
type control bits?". The answere is, you don't. Fortunately,
however, you don't have to. You can, instead of using control bits,
use alt-mode. One altmode preceding a character, has the same effect
as typing that character with <ctrl 1>. Two alt-modes is the same as
+<ctrl 2>, and three alt-modes is the same as <ctrl 12>. You can use
+the <ctrl 1>" feature to create long strings to be used in this
+fashion.
MULTI-STEP SPECIAL CONSIDERATIONS::::::::::::
When the multi-stepper gets to a subroutine call or return
instruction, is displays a big star and pauses, waiting for input.
If you type S it steps, if you type X it executes. Additionally, if
you type one of these two things, and control bits are on, special
things happen: if you type S with <ctrl 1>, then Raid will no longer
stop on subroutine calls, but will always step them. If you type S
with <ctrl 2>, then Raid will no longer stop at subroutine returns.
If you type S with <ctrl 12>, then both things happen. If you type X
with <ctrl 1>, then Raid will no longer stop at subroutine call, but
will always execute them. If you type X with <ctrl 2>, Raid will no
longer stop at subroutine returns. If you type X with <ctrl 12>,
both things happen. This state of affairs remains in effect until
you stop the stepping, or change it in the same way you set it,
except that it is clear at the start of each new multi-step command.